(This is part 2 of 3 of the Pocket Forth release 6.5 manual.)
Floating Point Numbers
Pocket Forth can recognize and manipulate floating point numbers. While this is not a standard Forth feature, the language is well served by this implementation (14), especially if your Macintosh has floating point hardware. The floating point routines will. however, run on any Macintosh.
Floating point numbers are implemented using the SANE software in the Macintosh system. SANE routines are fast and accurate. An available floating point chip is used by SANE automatically. This means, programs will benefit from its inclusion without needing specialized code.
Indicate that a token is a floating point number by including a decimal point or the letter 'e' in the number. The translator routine (part of SANE), is quite lenient, however the token must be a recognizable decimal or scientific notation number, ±INF or a NAN code as described by the Apple Numerics Manual (11). Examples of valid floating point numbers are: 3.1415926 42 . -0.0000012 6.626E-34 6.02e23 . BEWARE: Unknown tokens, such as 4U2 and -0X that start with numeral characters are also converted.
SANE extended floating point numbers are 80 bits long, so they occupy 10 bytes in memory, or 5 cells on the stack. Illustrate this by typing "1.0 . . . . . ".
figure 8
Words for working with floating point numbers are included. Many of these words are similar to integer words prefixed by 'f'. Words to manipulate floating point numbers on the stack ("fdrop", "fdup", "fswap", "fpick", "fpack" and "froll") and in memory ("f@", "f!", "fliteral", "f,", "fconstant" and "fvariable"), output them ("fix", "sci" and "f.") and convert them ("f>d", "d>f" and "fnumber") are all provided.
The sixteen math words make up the rest of the floating point suite. They are "f+", "f-", "f*", "f/", "frem", "f^", "fint", "fabs", "fsqrt", "fsin", "fcos", "ftan", "fexp", "fln" and "fcompare". The SANE financial functions are not included, but can be defined if needed. Refer to the glossary and the extension file, fvgFloatingPoint for more information.
Here is an example that calculates the area of a circle of a given diameter:
3.14159265359 fconstant PI
: ACIRCLE ( f.diameter -- f.area )
2. f/ fdup f* ( square the radius )
pi f* ; ( multiply it by pi )
13.6 acircle f.
Apple Events
The four required events, 'oapp', 'odoc', 'pdoc' and 'quit' are supported and installed at startup time. Your program may define additional event handlers, or redefine the required events. New events are added to the list to be installed the next time Pocket Forth is started.
To define an Apple Event, first put the event type and the event class double numbers on the stack, with ",s". Then use "ae:" and ";ae" to begin and end the definition. Write a procedure between them for the event handler. This process will attach the new definition to the tail of the Apple Events list. The defining word "ae:" handles the management of the Apple Event list so you do not need to deal with it.
Unlike the menu list, entries in the Apple Events list are installed into the system when the program starts up, and cannot be modified dynamically by your program. To install a new Apple Event, define the event then "save" the dictionary. (Be sure to use a copy of Pocket Forth!) Quit, then relaunch Pocket Forth and the new event handler is automatically installed.
When Pocket Forth receives an Apple Event, the AppleEvent and the Reply record addresses (absolute) are placed in the variables at "202 +md" and "198 +md". These addresses are used to extract information from, and respond to Apple Events. (10,13)
To see how this is done, check out the AppleEvents file and the HyperCard stack, AETest. This file defines 'do script', 'evaluate' and 'paste' events.
Here is an even simpler example. Make a copy of Pocket Forth and paste this in:
Reopen Pocket Forth, then use the AETest stack to send 'clos' to your new copy. The Pocket Forth window will disappear. You must Quit to reopen the window.
While this may not be useful, you have added a new Apple Event handler.
Errors are posted when an Apple Event sent to Pocket Forth is not handled properly. The error routine (address at "190 +md") is executed if an error occurred, with the error number on the stack. "Drop" is the default handler for the error routine. Install a sample error handler:
' aeerror 190 +md ! ( install error handler, no need to save this )
Send Pocket Forth an 'eval' event from the AETest stack. The error code for 'handler not installed' will be printed in Pocket Forth's window.
Pocket Forth contains an aete resource to let scripting programs know about the Apple Events it can handle.
Turnkey
In the Forth world, "turnkey" means to produce a stand alone program from the interpreter. Because most commercial Forth interpreters are proprietary, a side effect of turnkeying is that the interpreter is sealed off, and no longer available to the program's user.
For many programs, this is preferable since the interpreter can be confusing to many users. Pocket Forth can turnkey applications with or without this side effect.
The essence of the turnkey process is the assignment of new values to Pocket Forth's event and message handlers. Define a word with the correct actions, then place the address of the word in the unnamed variable used by the particular event or message. Use "save" to make the changes a permanent part of the program once it is debugged.
The button, activate and update events, idle and menu messages should be set as described in the events and menu sections.
The idle routine is run once each time through the event loop. As mentioned above the idle routine is used (non-destructivly) to defer actions set by some Apple Events, specifically the 'odoc' routine. See how to do that in the AppleEvents file.
The start up handler is executed after everything is setup and just before the interpreter loop is entered. You can write programs that do not give the user access to the interpreter. Do this by entering an endless event loop in the start up handler. Run time structures, such as data blocks, should be created in the startup handler.
The close handler is run when the close box of the window is clicked. The default close handler calls "bye" and returns, causing the application to quit by 'falling through' to the launching program (usually the Finder).
Key down events are not ignored, rather the application is centered around getting and handling key presses. The main event loop of Pocket Forth is called by the words "expect", "key" and "?terminal". Write an event loop for your program by embedding one of these words in a loop:
… EXPECT … ( handle all events until a return is typed )
... BEGIN KEY .. handle key data .. AGAIN ... ( endless event loop )
or ... BEGIN ... ?TERMINAL UNTIL ... ( a one shot event loop )
Run non-key events in their handler routines. Key events are handled in the event loop code. Here is the turnkey example:
( Handler demo application )
( Show the events as they are processed )
( The idle routine should only run once a second )
variable TLAST 0 tlast ! ( hold the last value of ticks here )
: TICKS ( -- n ) 364 0 l@ ; ( low word of 'ticks' system variable )
: ?1SEC ( -- flag ) ( true if >1 second has elapsed since last time )
ticks tlast @ - abs 60 > ; ( is time difference > 1 sec? )
." Idle" cr THEN ; ( wait 1 second between idle messages )
: MYACTIVATE ( flag -- ) IF ." Activated" ELSE ." Deactivated" THEN cr ;
: MYUPDATE ( -- ) ." Window updated" cr ;
: MYBUTTON ( -- ) ." Window clicked" cr ;
: MYKEY ( c -- ) emit space ." key pressed" cr ;
: MYCLOSE ( -- ) ." Closed" cr bye ;
: MYSTARTUP ( -- ) ." Hi There!" cr
BEGIN key ( "key" waits for a key press and runs event handlers )
mykey AGAIN ; ( Loop through the key handler indefinitely )
' mystartup 26 +md ! ( set the open handler )
' myclose 22 +md ! ( set the close handler )
' myidle 20 +md ! ( set the idle handler )
' mybutton 16 +md ! ( set the button handler )
' myupdate 14 +md ! ( set the update handler )
' myactivate 12 +md ! ; ( set activate handler )
page
( If this is not a copy, Quit! )
( ...Or hit a key to continue... ) key drop save bye
Once a turnkey program is finished, debugged, and all variables are initialized, save the dictionary, replacing the one stored on the disk. Then use ResEdit to change the resources such as the window title and the application's icon (as well as BNDL, FREF and signature resource) and About… item. Be sure to "save" only copies of Pocket Forth since the changes are permanent and cannot be undone.
The ReadMe application is an example of a turnkey program. Recompile ReadMe by using ResEdit to replace the DICT resource of (a copy of) ReadMe with a DICT copied from Pocket Forth. Save and close ReadMe from ResEdit. Launch ReadMe, which will open a Pocket Forth window. Load the file Reader by typing "open" (don't use the menu) and the ReadMe application will be rebuilt. (Type "by" to quit.)
Versions
The Pocket Forth version number is a three part number written as: T.V.S. 'T' is the program type, 'V' is the version within that type and 'S' is the subversion, indicating corrections within a version. Type 0 is an application with a sixteen bit stack and subroutine threading. The current version is 0.6.5.
Type 1 is a desk accessory. Version 1.6.5 is included with this release. Refer to the Manual Addendum inside of the desk accessory folder for details on the differences between the DA and the application.
Write to the author, Chris Heilman, if you have questions or comments.
Email: "heilman@pc.maricopa.edu"
CompuServe: [70566,1474]
AOL: cheilman
US Mail: PO box 8345
Phoenix, AZ 85066-8345
or visit the Pocket Forth site on the World Wide Web:
http://chemlab.pc.maricopa.edu/pocket.html
Bibliographic Notes:
(1) Barnhart, Joe, "FORTH and the Motorola 68000", Dr. Dobbs Journal no. 83, September 1983, Peoples Computer Company.
(2) Greene, Ronald, "Faster Forth", Byte v.9 no.6, June 1984, McGraw Hill Publishing Co.
(3) Loeliger, R. G. Threaded Interpretive Languages, Byte Books, 1981.
(4) Fletcher, G. Yates, "A Mini Forth for the 68000", Dr. Dobb's Journal no.123, January 1987, M&T Publishing, Inc. This article presents Flint, Forth interpreter in 68000 assembly language. Pocket Forth owes much of its structure and philosophy to Flint, and I thank Professor Fletcher and Dr. Dobb's Journal for publishing Flint.
(5) Ragsdale, William F., et al. fig-FORTH Installation Manual, release 1, Nov. 1980, Forth Interest Group. Includes Forth in Forth and source code for figFORTH.
(6) Derick, Mitch and Linda Baker FORTH Encyclopedia, Second Edition, Mountain View Press, Inc. 1982. This book shows the definitions of fig-FORTH words.
(7) Brodie, Leo Starting FORTH, FORTH, Inc. / Prentice Hall, 1981. The FORTH instruction manual and fun to read. You shouldn't learn Forth without this book.
(8) Chavez, Lori, "A Fast Forth for the 68000", Dr. Dobb's Journal no. 132, October 1987, M&T Publishing, Inc. This article describes how to implement macros.
(9) Knaster, Scott How to write Macintosh Software, Hayden Book Co., 1986
(10) Apple Computer Inc. Inside Macintosh, volume I through volume VI and X-Ref & Interapplication Communications, Addison Wesley, 1985-1993
(11) Apple Computer Inc. Apple Numerics Manual, Second Edition, Addison Wesley, 1988. This book describes SANE.
(12) Brodie, Leo Thinking Forth, Prentice Hall, 1984. The elements of code reusability are clearly explained, years before it became fashionable. Fun.
(13) Little, Gary & Tim Swihart, Programming for System 7, Addison Wesley, 1991 Geared toward C but useful none-the-less.
(14) Tracy, Martin, "Zen Floating Point", Dr. Dobb's Toolbook of Forth, volume II, M&T Publishing, 1987. Philosophical support for using floating point numbers on the stack.
